<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="generator" content="rustdoc">
    <title>Native Windows GUI guide - Derive events</title>

    <link rel="stylesheet" type="text/css" href="style/rustbook.css">
    <link rel="stylesheet" type="text/css" href="style/pygments.css">
    <link rel="stylesheet" type="text/css" href="style/nwg.css">


</head>
<body class="rustdoc">
<!--[if lte IE 8]>
<div class="warning">
    This old browser is unsupported and will most likely display funky
    things.
</div>
<![endif]-->

<!-- NAV BEGIN -->
<div id="nav">
    <button id="toggle-nav">
        <span class="sr-only">Toggle navigation</span>
        <span class="bar"></span>
        <span class="bar"></span>
        <span class="bar"></span>
    </button>
</div>

    
<div id='toc' class='mobile-hidden'>
<ul class='chapter'>
<li><a href='index.html'><b>1.</b> Introduction</a>
</li>
<li><a href='getting_started.html'><b>2.</b> Getting Started</a>
</li>

<li><a href="basics.html"><b>3.</b> Basics </a>
<ul class="section">
    <li><a href="controls.html"><b>3.1.</b> Controls </a></li>
    <li><a href="events.html"><b>3.2.</b> Events </a></li>
    <li><a href="helper.html"><b>3.3.</b> Helpers </a></li>
    <li><a href="small.html"><b>3.4.</b> Small application layout </a></li>
    <li><a href="limitations.html"><b>3.5.</b> Limitations </a></li>
    <li><a href="distribute.html"><b>3.6.</b> Distributing </a></li>
    <li><a href="features.html"><b>3.7.</b> Features </a></li>
</ul>
</li>

<li><a href="intermediate.html"><b>4.</b> Intermediate </a>
<ul class="section">
    <li><a href="layouts.html"><b>4.1.</b> Layouts </a></li>
    <li><a href="resources.html"><b>4.2.</b> Resources </a></li>
    <li><a href="dialogs.html"><b>4.3.</b> Dialogs </a></li>
    <li><a href="localization.html"><b>4.4.</b> Internationalization </a></li>
</ul>
</li>

<li><a href="advanced.html"><b>5.</b> Advanced </a>
<ul class="section">
    <li><a href="partial.html"><b>5.1.</b> Partials ui </a></li>
    <li><a href="dynamic_control.html"><b>5.2.</b> Dynamic control </a></li>
    <li><a href="dynamic_event.html"><b>5.3.</b> Dynamic events </a></li>
    <li><a href="multithreading.html"><b>5.4.</b> Multithreading </a></li>
</ul>
</li>

<li><a href="derive.html"><b>6.</b> Native-windows-derive </a>
<ul class="section">
    <li><a href="nwd_basics.html"><b>6.1.</b> Basics </a></li>
    <li><a href="nwd_controls.html"><b>6.1.</b> Controls </a></li>
    <li><a href="nwd_resources.html"><b>6.2.</b> Resources </a></li>
    <li><a href="nwd_events.html"><b>6.3.</b> Events </a></li>
    <li><a href="nwd_layouts.html"><b>6.4.</b> Layouts </a></li>
    <li><a href="nwd_partial.html"><b>6.5.</b> Partials </a></li>
</ul>
</li>

<li><a href="low.html"><b>7.</b> Low level stuff </a>
    <ul class="section">
        <li><a href="low_events.html"><b>7.1.</b> Raw event handling </a></li>
        <li><a href="extern_wrapping.html"><b>7.2.</b> Raw control handle </a></li>
    </ul>
</li>

</ul>
</div>
<!-- NAV END -->

<div id='page-wrapper'>
    <div id='page'>

        <h1 class="title">Native Windows Derive: Events</h1>

        After defining the controls, it's time to bind the events. Every events defined in a Ui struct will be regrouped in
        a single event hook.

        <h3>Events base</h3>

        Events are bound to control using the <code>nwg_events</code> attribute. It takes a list of event type and event callbacks.<br><br>

        Template: <br>
        <code>nwg_events( EVENT_TYPE: [CALLBACK(ARGS),*] )</code><br><br>

        Details: <br>
        <ul>
            <li><b>EVENT_TYPE</b> is any value of the <code>Event</code> enum.</li>
            <li><b>CALLBACK</b> is the function that will be called when the event is triggered.</li>
            <li><b>ARGS</b> specifies the parameters of the callback (optional, see the next section).</li>
        </ul>
        <br>

        Example:
<div class="highlight"><pre style="width: auto;"><span></span><span class="cp">#[nwg_events(</span>
<span class="cp">    OnButtonClick: [TestApp::callback1, TestApp::callback2]</span><span class="p">,</span><span class="w"></span>
<span class="w">    </span><span class="n">OnMouseMove</span>: <span class="p">[</span><span class="n">TestApp</span>::<span class="n">callback3</span><span class="p">(</span><span class="n">SELF</span><span class="p">,</span><span class="w"> </span><span class="n">CTRL</span><span class="p">)]</span><span class="w"></span>
<span class="p">)]</span><span class="w"></span>
<span class="n">window</span>: <span class="nc">nwg</span>::<span class="n">Button</span><span class="p">,</span><span class="w"></span>
</pre></div>
            
        <h3>Events arguments</h3>

        By default, native windows derive assumes the callback is a method of the Ui structure. So for example,
        <code>TestApp::callback1</code> assumes the method has the following signature <code>callback1(&self)</code>.<br><br>

        That's very limiting. For example, if the same callback is used by two different controls, there's no way to differenciate them.
        In order to fix this, NWD lets you define the callbacks parameters using those identifiers:

        <ul>
            <li><b>SELF</b>: Sends the ui struct <code>&UiStruct</code>. If there are no parameters, this is the default. </li>
            <li><b>RC_SELF</b>: Sends the rc ui struct <code>&Rc&lt;UiStruct&gt;</code>. Useful for binding dynamic events</li>
            <li><b>CTRL</b>: Sends the control that triggered the event. Ex: <code>&Button</code></li>
            <li><b>HANDLE</b>: Sends the handle of the control. <code>&ControlHandle</code></li>
            <li><b>EVT</b>: Sends the event that was triggered. <code>&Event</code></li>
            <li><b>EVT_DATA</b>: Sends the <i>data</i> of the event that was triggered. <code>&EventData</code></li>
        </ul>

        It's also possible to not use any parameters, ex: <code>TestApp::callback1()</code>.

        <h3>Example</h3>

<div class="highlight"><pre><span></span><span class="k">pub</span><span class="w"> </span><span class="k">struct</span> <span class="nc">Demo</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="c1">//...</span>
<span class="w">    </span><span class="cp">#[nwg_events(</span>
<span class="cp">        OnButtonClick: [Demo::button1, Demo::button2]</span><span class="p">,</span><span class="w">            </span><span class="c1">// Multiple callbacks</span>
<span class="w">        </span><span class="n">OnMouseMove</span>: <span class="p">[</span><span class="n">Demo</span>::<span class="n">moving</span><span class="p">(</span><span class="n">SELF</span><span class="p">,</span><span class="w"> </span><span class="n">CTRL</span><span class="p">),</span><span class="w"> </span><span class="n">Demo</span>::<span class="n">move2</span><span class="p">()],</span><span class="w">   </span><span class="c1">// With custom params &amp; for a static method</span>
<span class="w">    </span><span class="p">)]</span><span class="w"></span>
<span class="w">    </span><span class="n">add_message_btn</span>: <span class="nc">nwg</span>::<span class="n">Button</span><span class="p">,</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</pre></div>
            
        <br/>
        Some events are defined as sub enums (ex: <code>MousePress</code>). In those case, the sub enums values must be used. For example,
        if someone wants to handle a "left up events", a code similar to this should be used:

<div class="highlight"><pre style="width: auto;"><span></span><span class="k">pub</span><span class="w"> </span><span class="k">struct</span> <span class="nc">Demo</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="cp">#[nwg_control]</span><span class="w"></span>
<span class="w">    </span><span class="cp">#[nwg_events(MousePressLeftUp: [Demo::test]</span><span class="p">,)]</span><span class="w"></span>
<span class="w">    </span><span class="n">frame1</span>: <span class="nc">nwg</span>::<span class="n">Frame</span><span class="p">,</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</pre></div>
            

        <br/><br/>

    </div>
</div>

<script src="style/rustbook.js"></script>
</body>
</html>
